Morpheus Gateway

https://wiki.uracle.co.kr/madp/server/gw/server/run-application
Admin
Morpheus Gateway is a middleware solution offering REST API server, App deployment, event logging,...
Tokens:5,018
Snippets:23
Trust Score:7.5
Update:1 year ago
Show doc for...
Tokens:
Raw
### MSP Gateway Sample Configuration Examples

Source: https://wiki.uracle.co.kr/madp/server/gw/server/run-application/server/gw/server/run-application

Provides various sample configurations for file operations and HTTP proxying within the MSP Gateway. This includes settings for file upload/download locations, HTTP server URLs for API proxy requests, legacy system download URLs, and push service API proxy URLs.

Properties:
- `file.upload.location`: Local path used for file uploads and downloads (Refer: `FileService.java`).
- `http.server.url`: Server URL used when making API proxy requests via RestTemplate (Refer: `HttpProxyController.java`).
- `http.legacy.url`: Base URL for downloading files from legacy systems (Refer: `HttpProxyDownloadService.java`).
- `http.legacy.download`: Local path to save files downloaded from legacy systems (Refer: `HttpProxyDownloadService.java`).
- `http.push.url`: Base URL used for proxy requests to the push service API (Refer: `PushController.java`).

```YAML
file:
  upload:
    location: /Users/uracle/temp/upload

http:
  server:
    url: http://localhost:9090
  legacy:
    url: http://localhost:8080/msp-gw/api/file/download/
    download: /Users/uracle/temp/download/
  push:
    url: http://127.0.0.1:8380
```

--------------------------------

### Example JSON Request for Book Search

Source: https://wiki.uracle.co.kr/madp/server/gw/server/run-application/server/gw/server/run-application

Illustrates the structure of a JSON request to search for books. The 'head' object is for common request headers, and the 'body' contains search parameters like 'title'.

```JSON
{
    "head": {
    },
    "body": {
      "title": "life"
    }
}
```

--------------------------------

### Example JSON Response for Book List

Source: https://wiki.uracle.co.kr/madp/server/gw/server/run-application/server/gw/server/run-application

Shows the structure of a successful JSON response for a book list query. The 'head' contains the result code and message, while the 'body' is an array of 'BookList' objects, each representing a book with details.

```JSON
{
    "head": {
      "result_code": "200",
      "result_msg": "조회 성공"
    },
    "body": [
      {
        "bookId": "4",
        "title": "What Life Was Like in the Jewel in the Crown: British India  AD 1600-1905",
        "isbn13": "34406054602",
        "languageName": "English",
        "numPages": "168",
        "publicationDate": "1999-09-01",
        "publisherName": "Time Life Medical",
        "authorName": "Time-Life Books"
      },
      {
        "bookId": "6",
        "title": "Life Is a Dream and Other Spanish Classics (Eric Bentley's Dramatic Repertoire) - Volume II",
        "isbn13": "73999140774",
        "languageName": "English",
        "numPages": "298",
        "publicationDate": "2000-04-01",
        "publisherName": "Applause Theatre and Cinema Book Publishers",
        "authorName": "Eric Bentley"
      }
    ]
}
```

--------------------------------

### MSP Gateway Event Log File Format Example

Source: https://wiki.uracle.co.kr/madp/server/gw/server/run-application/server/gw/server/run-application

An example of the log content generated in `stat_{yyyyMMdd}.log` files when event logging is enabled. Each field is separated by a pipe ('|').

```Text
0|1.0|TEST_APP|26|Android|111111223333338|SM-N960F|01099999999|/api/res/auto-update||PostmanRuntime/7.36.0|0:0:0:0:0:0:0:1|2024-01-16 10:40:12||||com.uracle.push.demo
```

--------------------------------

### MSP Gateway Resource Download Configuration

Source: https://wiki.uracle.co.kr/madp/server/gw/server/run-application/server/gw/server/run-application

Configures settings for checking and downloading the latest resource files. This includes options to force HTTPS, specify a custom HTTPS port, define the download URL, and select the download type (filename for direct download or file_id for WAS-based download).

Properties:
- `use-force-https`: (true/false) Determines if the resource zip file download URL is always provided via HTTPS, regardless of the request protocol.
- `https-port`: Specifies the port if HTTPS is used and it's not the default port.
- `download-url`: The URL for resource download. If not specified, the client's connection URL is used.
- `download-type`: Selects the resource download method.
  - `filename`: (Default) Direct download of the zip file using NAS or an HTTP server (includes filename, GET method).
  - `file_id`: Sends a file ID to WAS for download (does not use the zip file name).

```YAML
msp:
  gateway:
    resource-update:
      use-force-https: true
      https-port: 443
      download-url:
      download-type: filename
```

--------------------------------

### Morpheus Gateway Sample REST API List

Source: https://wiki.uracle.co.kr/madp/server/gw/server/run-application/server/gw/server/run-application

Provides a list and description of sample REST APIs offered by msp-gw-boot-web, including user information lookup, file upload, HTTP proxy, and push message integration.

```APIDOC
Package: kr.msp.example.basic
  - API URL: /
    HTTP Method: GET
    Description: index.jsp 페이지를 반환하는 기본 메인 엔드포인트입니다. 브라우저 테스트 용도로 사용됩니다.
  - API URL: /api/basic/sample/userList
    HTTP Method: GET
    Description: SAMPLE_USER 테이블 전체 데이터를 조회하고 userList.jsp로 전달하여 화면에 렌더링합니다.
  - API URL: /api/basic/sample/{id}
    HTTP Method: GET
    Description: 경로 변수 id에 해당하는 사용자 정보를 조회하고, 결과를 JSON 형태로 반환합니다. 데이터가 없으면 204 No Content 응답을 반환합니다.
  - API URL: /api/basic/sample/list
    HTTP Method: GET
    Description: 사용자 정보를 Map 형태의 리스트 (List<Map<String, Object>>)로 반환합니다. 동적 필드 구조가 필요한 경우에 적합합니다.
  - API URL: /api/basic/sample/dto/list
    HTTP Method: GET
    Description: 사용자 정보를 User DTO 형태의 리스트 (List<User>)로 반환합니다. 정적 타입 기반 API 설계에 적합합니다.
  - API URL: /api/basic/sample/config
    HTTP Method: GET
    Description: application.yml 설정 값을 조회하는 디버깅용 API입니다. 운영환경에서는 노출을 제한하는 것이 권장됩니다.

Package: kr.msp.example.file
  - API URL: /api/file/upload
    HTTP Method: POST
    Description: multipart/form-data 방식으로 파일을 업로드합니다. 파일은 file.upload.location 경로에 저장됩니다.
  - API URL: /api/file/download/{fileExtension}/{fileId}
    HTTP Method: GET
    Description: 지정된 파일 ID에 해당하는 파일을 다운로드합니다. fileExtension은 클라이언트에서의 저장 확장자입니다.

Package: kr.msp.example.http
  - API URL: /api/proxy/sample
    HTTP Method: POST
    Description: 내부 RestTemplate을 통해 외부 API 서버에 요청을 프록시합니다. 테스트 또는 연동용으로 사용됩니다.
  - API URL: /api/http/legacy/proxy
    HTTP Method: POST
    Description: http.legacy.url 설정을 기반으로 레거시 시스템에 API 또는 파일 요청을 수행합니다.
  - API URL: /api/proxy/download/{fileExtension}/{fileId}
    HTTP Method: GET
    Description: 레거시 시스템에서 지정된 파일을 다운로드합니다. 다운로드 경로는 http.legacy.download 설정을 따릅니다.
  - API URL: /api/push/user/regist
    HTTP Method: POST
    Description: 푸시 서비스 가입 및 사용자 등록 요청을 외부 PUSH 서비스로 프록시합니다.
  - API URL: /api/push/send
    HTTP Method: POST
    Description: 외부 푸시 시스템에 푸시 메시지를 전송하는 API입니다. 대상과 메시지 정보를 JSON으로 전달해야 합니다.
```

--------------------------------

### MSP Gateway In-House App Store Configuration

Source: https://wiki.uracle.co.kr/madp/server/gw/server/run-application/server/gw/server/run-application

Configures the settings required for using the in-house app distribution feature (App Store). This includes defining the Web Admin URL for app downloads, the binary path, and the physical directory where distributed apps will be stored.

Properties:
- `bin-path`: The binary path for the application.
- `service-path`: The Web Admin URL from which distributed apps can be downloaded (Admin page address + ContextRoot).
- `upload-path`: The full physical directory path where apps to be distributed from the store will be saved (parent directory of the web server's WEB-INF).

```YAML
msp:
  gateway:
    app-store:
      service-path: http://127.0.0.1/msp-admin/
      bin-path: apk
      upload-path: /apps/msp-admin/
```

--------------------------------

### Java Spring Boot Controller for Book List API

Source: https://wiki.uracle.co.kr/madp/server/gw/server/run-application/server/gw/server/run-application

This Spring '@PostMapping' method handles requests to '/api/book/list'. It retrieves book data using 'bookService', sets a success response header, and returns a 'ResponseEntity' containing the list of books.

```Java
@PostMapping(value = "/api/book/list")
public ResponseEntity<Response<ResponseHeader, List<BookList>>> getBooKList(
    Request<RequestHeader, BookParameter> request) {
    List<BookList> bookList = bookService.getBookList(request.getBody());

    ResponseHeader responseHeader = new ResponseHeader();
    responseHeader.setResultCode(ResponseCode.OK);
    responseHeader.setResultMessage(Const.SUCCESS);
    return ResponseEntity.ok(new Response<>(responseHeader, bookList));
}
```

--------------------------------

### Spring Boot Web Application Directory Structure

Source: https://wiki.uracle.co.kr/madp/server/gw/server/run-application/server/gw/server/run-application

This snippet provides a comprehensive overview of the directory and file organization within a Spring Boot web application. It details the placement of source code, Maven project settings, README, configuration files (application.yml, log4j2.xml), SQL mappers, static assets, and web application resources like JSP files and license certificates. Key components like the main application entry point, various controllers, services, DTOs, and utility classes are clearly mapped within their respective packages.

```plaintext
/msp-gw-boot-web
├── pom.xml                                  # Maven 프로젝트 설정 파일
├── README.md                                # 프로젝트 설명 문서
├── src                                      # 소스 코드 디렉토리
│   ├── main
│   │   ├── java
│   │   │   └── kr
│   │   │       └── msp
│   │   │           ├── WebApplication.java              # Spring Boot 애플리케이션 진입점
│   │   │           ├── config
│   │   │           │   ├── PropertyConfig.java          # 설정 프로퍼티 로더
│   │   │           │   └── WebConfig.java               # 웹 MVC 관련 설정
│   │   │           ├── example
│   │   │           │   ├── basic
│   │   │           │   │   ├── SampleController.java    # 샘플 REST 컨트롤러
│   │   │           │   │   ├── SampleMapper.java        # 샘플 MyBatis 매퍼 인터페이스
│   │   │           │   │   ├── SampleService.java       # 샘플 비즈니스 로직 서비스
│   │   │           │   │   ├── dto
│   │   │           │   │   │   └── User.java            # 사용자 DTO
│   │   │           │   │   └── util
│   │   │           │   │       └── PropertiesUtil.java  # 환경 설정 유틸 클래스
│   │   │           │   ├── file
│   │   │           │   │   ├── FileInfo.java            # 파일 메타정보 DTO
│   │   │           │   │   ├── FileProperties.java      # 파일 처리 관련 프로퍼티
│   │   │           │   │   └── FileService.java         # 파일 처리 서비스
│   │   │           │   └── http
│   │   │           │       ├── HttpProperties.java      # HTTP 관련 프로퍼티 설정
│   │   │           │       ├── controller
│   │   │           │       │   ├── HttpProxyController.java  # 프록시 API 컨트롤러
│   │   │           │       │   └── PushController.java       # 푸시 API 컨트롤러
│   │   │           │       ├── dto
│   │   │           │       │   ├── HttpResponse.java         # 프록시 응답 DTO
│   │   │           │       │   ├── PushResult.java           # 푸시 결과 DTO
│   │   │           │       │   ├── PushSendResult.java       # 푸시 전송 결과 DTO
│   │   │           │       │   ├── RequestParameter.java     # 프록시 요청 파라미터
│   │   │           │       │   └── Result.java               # 공통 결과 DTO
│   │   │           │       ├── service
│   │   │           │       │   ├── HttpProxyDownloadService.java  # 레거시 파일 다운로드 서비스
│   │   │           │       │   ├── HttpProxyLegacyService.java    # 레거시 파일 핸들러
│   │   │           │       │   ├── HttpProxyService.java          # HTTP 프록시 비즈니스 로직
│   │   │           │       │   └── PushService.java               # 푸시 메시지 전송 서비스
│   │   │           │       └── tcp
│   │   │           │           ├── TcpAliveManager.java           # TCP 연결 상태 관리
│   │   │           │           └── TcpAliveThread.java            # TCP Alive 스레드
│   ├── resources
│   │   ├── application.yml                     # 애플리케이션 설정 파일
│   │   ├── log4j2.xml                          # 로그 설정 파일
│   │   ├── sqlmap
│   │   │   └── oracle
│   │   │       └── sample
│   │   │           └── sample.xml              # 샘플 Mapper XML (SQL 정의)
│   │   ├── static
│   │   │   └── css
│   │   │       └── sample.css                  # 샘플 스타일시트
│   │   └── WEB-INF
│   │       └── config
│   │           ├── license.cer                 # 라이선스 인증서 파일
│   │           └── license.key                 # 라이선스 키 파일
│   └── webapp
│       └── WEB-INF
│           └── jsp
│               ├── index.jsp                   # 메인 페이지 JSP
│               └── userList.jsp                # 사용자 리스트 JSP
```

--------------------------------

### Java Service Implementation with SqlSessionTemplate

Source: https://wiki.uracle.co.kr/madp/server/gw/server/run-application/server/gw/server/run-application

This 'BookService' implementation uses 'SqlSessionTemplate' for database access, typically when 'msp.gateway.datasource' is configured. It injects 'SqlSessionTemplate' and retrieves a 'BookMapper' instance to fetch book lists.

```Java
@Service
public class BookService {

    private final SqlSessionTemplate sqlSessionTemplate;

    public BookService(SqlSessionTemplate sqlSessionTemplate){
        this.sqlSessionTemplate = sqlSessionTemplate;
    }

    public List<BookList> getBookList(BookParameter bookparameter) {
       BookMapper bookMapper = sqlSessionTemplate.getMapper(BookMapper.class);
       return bookMapper.getBookList(bookparameter);
    }
}
```

--------------------------------

### Java Service Implementation with Direct Mapper Injection

Source: https://wiki.uracle.co.kr/madp/server/gw/server/run-application/server/gw/server/run-application

An alternative 'BookService' implementation where 'BookMapper' is directly injected, common when 'spring.datasource' is configured. This simplifies the 'getBookList' method by directly calling the mapper.

```Java
@Service
public class BookService {

    private final BookMapper bookMapper;

    public BookService(BookMapper bookMapper) {
       this.bookMapper = bookMapper;
    }

    public List<BookList> getBookList(BookParameter bookparameter) {
       return bookMapper.getBookList(bookparameter);
    }
}
```

--------------------------------

### BookParameter Class Details

Source: https://wiki.uracle.co.kr/madp/server/gw/server/run-application/server/gw/server/run-application

Details the 'BookParameter' DTO object, which contains conditions for book information queries and is placed in the 'body' field of the 'Request' class.

```APIDOC
BookParameter:
  Purpose: DTO object containing conditions for book information queries (e.g., title, author).
  Usage: Placed in the 'body' field of the Request class.
```

--------------------------------

### RequestHeader Class Details

Source: https://wiki.uracle.co.kr/madp/server/gw/server/run-application/server/gw/server/run-application

Details the 'RequestHeader' class, which holds client request information and is placed in the 'head' field of the 'Request' class.

```APIDOC
RequestHeader:
  Purpose: Contains common request header information like device, app, and user details.
  Usage: Placed in the 'head' field of the Request class.
```

--------------------------------

### BookList Class Details

Source: https://wiki.uracle.co.kr/madp/server/gw/server/run-application/server/gw/server/run-application

Details the 'BookList' DTO object, which holds book information retrieved from the database. It is placed in the 'body' field of the 'Response' class.

```APIDOC
BookList:
  Purpose: DTO object containing book information retrieved from the database.
  Usage: Placed in the 'body' field of the Response class.
  Properties (from JSON example):
    bookId: string
    title: string
    isbn13: string
    languageName: string
    numPages: string
    publicationDate: string
    publisherName: string
    authorName: string
```

--------------------------------

### Java Mapper Interface for Book Data Access

Source: https://wiki.uracle.co.kr/madp/server/gw/server/run-application/server/gw/server/run-application

The 'BookMapper' interface, annotated with '@Mapper', defines the contract for database operations related to books. It includes the 'getBookList' method for retrieving a list of 'BookList' objects based on 'BookParameter'.

```Java
  @Mapper
public interface BookMapper {
    List<BookList> getBookList(BookParameter bookparameter);
}
```

--------------------------------

### MSP Gateway Database Connection Configuration

Source: https://wiki.uracle.co.kr/madp/server/gw/server/run-application/server/gw/server/run-application

Configures the database connection settings for the MSP Gateway, including the Oracle JDBC driver, connection URL, username, and password. It also specifies the classpath for MyBatis mapper XML files.

```YAML
msp:
  gateway:
    datasource:
      driver-class-name: oracle.jdbc.OracleDriver
      url: jdbc:oracle:thin:@127.0.0.1:1521:UDB
      username: lab
      password: lab
    mybatis:
      mapper-locations: classpath:/sqlmap/oracle/**/*.xml
```

--------------------------------

### API Response Object Structure

Source: https://wiki.uracle.co.kr/madp/server/gw/server/run-application/server/gw/server/run-application

Defines the generic 'ResponseEntity' wrapping a 'Response' object for API replies. It includes a 'ResponseHeader' for status and a list of 'BookList' objects as the actual data payload.

```APIDOC
ResponseEntity<Response<ResponseHeader, List<BookList>>>
  ResponseHeader: Contains processing result code and message.
  body: Actual list of book information (List<BookList>).
```

--------------------------------

### API Request Object Structure

Source: https://wiki.uracle.co.kr/madp/server/gw/server/run-application/server/gw/server/run-application

Defines the generic 'Request' object used for API calls. It comprises a 'RequestHeader' for common information and a 'BookParameter' for specific request body data.

```APIDOC
Request<RequestHeader, BookParameter>
  RequestHeader: Common request header information (device, app, user info).
  BookParameter: Domain object containing search conditions (e.g., book title, author).
```

--------------------------------

### MSP Gateway Event Log Field Descriptions

Source: https://wiki.uracle.co.kr/madp/server/gw/server/run-application/server/gw/server/run-application

A mapping of the fields found in the event log file, separated by a pipe ('|'), to their respective meanings. These fields are parsed and stored in the database daily.

```Text
|Number|App Version|App Name|System Version|System Name|Device ID|Device Model|Phone Number|Company Code|Service Code|User Agent|Host|Creation Time|User ID|User Name|Page Name|App ID
```

--------------------------------

### MSP Gateway Event Log Stored File Naming Convention

Source: https://wiki.uracle.co.kr/madp/server/gw/server/run-application/server/gw/server/run-application

Illustrates the naming convention for event log files after they have been processed and stored in the database. The format is `stat_{yyyyMMdd}.log.stored_yyyyMMddHH24mmss_index`.

```Text
stat_20240227.log.stored_20240228160100_1
```

--------------------------------

### ResponseHeader Class Details

Source: https://wiki.uracle.co.kr/madp/server/gw/server/run-application/server/gw/server/run-application

Details the 'ResponseHeader' object, which includes the result code ('result_code') and result message ('result_msg') of an API operation. It is placed in the 'head' field of the 'Response' class.

```APIDOC
ResponseHeader:
  Purpose: Object containing result code (result_code) and result message (result_msg).
  Usage: Placed in the 'head' field of the Response class.
```

--------------------------------

### MSP Gateway Event Logging Configuration

Source: https://wiki.uracle.co.kr/madp/server/gw/server/run-application/server/gw/server/run-application

Enables and configures the event logging feature for API requests, capturing parameters and request URLs. Logging occurs after API request processing is complete. This configuration defines the log file path, enables/disables logging, and sets the cron schedule for batch processing.

Properties:
- `path`: The directory path where event logs will be stored.
- `enabled`: (true/false) Determines whether event logging is active.
- `cron`: The cron expression for the event log batch processing cycle.

```YAML
msp:
  gateway:
    event-log:
      path: /Users/uracle/temp/log/msp-gw/eventlogs/
      enabled: true
      cron: 0 0/30 * * * ?
```

--------------------------------

### Morpheus Gateway Custom Request/Response Structure

Source: https://wiki.uracle.co.kr/madp/server/gw/server/run-application/server/gw/server/run-application

Explains the interaction method for REST API development using Morpheus Gateway's custom Request/Response structure. Clients send requests using a combination of RequestHeader and body, and the server responds with a Response object including ResponseHeader (with status code) and body. Response codes use ResponseCode enum for clarity. Objects are flexible via generics and builder patterns.

```APIDOC
Morpheus Gateway Custom Request/Response Structure:
  - Client Request: RequestHeader + Body -> Request Object
  - Server Response: ResponseHeader (includes status code) + Body -> Response Object
  - Status Codes: Use ResponseCode enum
  - Flexibility: Generics and Builder Pattern support
```
Tokens:
Raw